keychainmanager.htmlHTMLudogä˘πùΔ£πùΔ£ÅÅ€ñ Monkeybread Realbasic plugin - Documentation - KeyChainManager

MBS Plugin Documentation

This is the documentation for the Realbasic Plugins from Monkeybreadsoftware.de. You find these plugins and the newest version of this document at http://www.monkeybreadsoftware.de/realbasic inside the plugins section.

This help was last updated on Freitag, 6. September 2002 and covers 2136 items: 126 classes, 2 controls and 583 global functions.

The list of the themes Global methods by category Global methods by name The list of the classes The list of the controls

class KeyChainManager
class, KeyChain Plugin version: 2.6 So, 1. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: A class for the functions of the keychain manager.

AddGenericPassword(parameter as KeyChainRequest) as KeyChainItem
method, KeyChain Plugin version: 2.6 Di, 3. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Adds a new generic password to the default keychain.
Notes:
The AddGenericPassword function adds a new generic password to the default keychain. Required parameters to identify the password are serviceName and accountName, which are application-defined strings. AddGenericPassword returns a reference to the newly added item.

You can use AddGenericPassword to add passwords for accounts other than Internet or Appleshare. For example, you might add passwords for your database or scheduling programs.

From the KeyChainRequest object, the properties servicename, accountname and password.

LastError is set.

AddInternetPassword(parameter as KeyChainRequest) as KeyChainItem
method, KeyChain Plugin version: 2.6 Di, 3. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Adds a new Internet server password to the default keychain.
Notes:
The AddInternetPassword function adds a new Internet server password to the default keychain. Required parameters to identify the password are serviceName and accountName (you cannot pass "" for both parameters). In addition, some protocols may require an optional securityDomain when authentication is requested. AddInternetPassword returns a reference to the newly added item.

AddInternetPassword will automatically call the Unlock function to display the Unlock Keychain dialog box if the keychain containing the password is currently locked.

From the KeyChainRequest object, the properties servername, securitydomain, accountname, port, protocol, authtype and password.

LastError is set.

AddInternetPasswordWithPath(parameter as KeyChainRequest) as KeyChainItem
method, KeyChain Plugin version: 2.6 Di, 3. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Adds a new Internet server password with a specified path to the default keychain.
Notes:
The AddInternetPasswordWithPath function enables you to specify path information when adding a new Internet server password to the default keychain. Required parameters to identify the password are serviceName and accountName (you cannot pass "" for both parameters). In addition, some protocols may require an optional securityDomain when authentication is requested. AddInternetPasswordWithPath returns a reference to the newly added item.

AddInternetPasswordWithPath will automatically call the unlock function to display the Unlock Keychain dialog box if the keychain containing the password is currently locked.

From the KeyChainRequest object, the properties servername, securitydomain, accountname, path, port, protocol, authtype and password.

LastError is set.

available as boolean
property, KeyChain Plugin version: 2.6 So, 1. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways false.
Function: Wether the keychain manager is available.

CountKeychains as integer
method, KeyChain Plugin version: 2.6 So, 1. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Determines the number of available keychains.
Notes:
This function reports the number of keychains known to the Keychain Manager. These keychains are created by the function CreateKeychain and placed in the Keychains Folder in the Preferences Folder, inside the active System Folder.

function result:
The number of available keychains. This includes all keychains in the Keychains folder, as well as any other keychains known to the Keychain Manager.

LastError is set.

CreateKeyChain(password as string) as KeyChain
method, KeyChain Plugin version: 2.6 So, 1. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Creates an empty keychain.
Notes:
Password is a string representing the password string which will be used to protect the new keychain. If you pass "", the Keychain Setup dialog box will be displayed to obtain it.

The CreateKeychain function creates an empty keychain. The keychain and password parameters are optional. If user interaction to create a keychain is posted, the newly-created keychain is automatically unlocked after creation.

LastError is set.

DefaultKeyChainChangeSettings
method, KeyChain Plugin version: 2.6 Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Displays a dialog box enabling the user to change the name, password, or settings of the default keychain.
Notes:
Typically, your application should not call the ChangeSettings function. You would only call ChangeSettings in response to a user's request to change keychain settings, name, or password. Note that you cannot change a keychain passphrase directly. You must call ChangeSettings and allow the user to change it.

LastError is set.

DefaultKeyChainStatus as integer
property, KeyChain Plugin version: 2.6 So, 1. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Returns the current state of the default keychain.
Notes:
LastError is set.

Constants:

kSecUnlockStateStatus1Indicates the keychain is unlocked.
kSecRdPermStatus2Indicates the keychain is read-only.
kSecWrPermStatus4Indicates the keychain is writable.

FindGenericPassword(parameter as KeyChainRequest) as KeyChainItem
method, KeyChain Plugin version: 2.6 Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Finds the first Internet password in the default keychain that matches the specified parameters.
Notes:
The FindGenericPassword function finds the first password item which matches the attributes you provide. FindGenericPassword returns a reference to the found item.

FindGenericPassword will automatically call the unlock function to display the Unlock Keychain dialog box if the keychain containing the password is currently locked.

From the KeyChainRequest object, the properties servicename, accountname, and password. (password is set if the function is successfull.)

servicename and accountname maybe "" to match any value.

LastError is set.

FindInternetPassword(parameter as KeyChainRequest) as KeyChainItem
method, KeyChain Plugin version: 2.6 Di, 3. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Finds the first Internet password in the default keychain that matches the specified parameters.
Notes:
The FindInternetPassword function finds the first Internet password item which matches the attributes you provide. FindInternetPassword returns a reference to the found item.

FindInternetPassword will automatically call the unlock function to display the Unlock Keychain dialog box if the keychain containing the password is currently locked.

From the KeyChainRequest object, the properties servername, securitydomain, accountname, port, protocol, authtype and password. (password is set if the function is successfull.)

Servername, securitydomain, protocol, authtype and accountname maybe "" to match any value. Port may be 0 to match any port value.

LastError is set.

FindInternetPasswordWithPath(parameter as KeyChainRequest) as KeyChainItem
method, KeyChain Plugin version: 2.6 Di, 3. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Finds the first Internet password in the default keychain that matches the specified parameters.
Notes:
The FindInternetPasswordWithPath function finds the first Internet password item which matches the attributes you provide. FindInternetPasswordWithPath returns a reference to the found item.

FindInternetPasswordWithPath will automatically call the unlock function to display the Unlock Keychain dialog box if the keychain containing the password is currently locked.

From the KeyChainRequest object, the properties servername, securitydomain, accountname, path, port, protocol, authtype and password. (password is set if the function is successfull.)

Servername, securitydomain, path, protocol, authtype and accountname maybe "" to match any value. Port may be 0 to match any port value.

LastError is set.

InteractionAllowed as boolean
property, KeyChain Plugin version: 2.6 So, 1. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways false.
Function: Wether the Keychain manager is allowed to show dialogs to ask the user.
Notes: LastError is set.

KeyChainFindFirst(kc as KeyChain) as KeyChainSearchItem
method, KeyChain Plugin version: 2.6 Di, 3. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Finds the first keychain item in a specified keychain.
Notes:
The parameter kc is the keychain that you wish to search. If you pass a locked keychain, the Unlock Keychain dialog box is displayed. If you pass nil, KeyChainFindFirst search all unlocked keychains.

Returns an object of the KeyChainSearchItem class with the first found item in the item property. Returns nil on any error.

LastError is set.

LastError as integer
property, KeyChain Plugin version: 2.6 So, 1. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: The number representing the last error reported.
Notes:
If a function is not available (e.g. KeyChain Manager not installed), the lasterror property has the value -1. If the plugin was unable to allocate memory, -2 is returned.

KeyChain Manager error codes:

errKCNotAvailable-25291Indicates that the Keychain Manager was not loaded.
errKCReadOnly-25292Returned by the function KCCopyItem to indicate that the keychain file is read-only and cannot be edited.
errKCAuthFailed-25293Returned by the function KCUnlock to indicate that the authentication failed (too many unsuccessful retries).
errKCNoSuchKeychain-25294Returned by the functions KCUnlock, KCSetDefaultKeychain, KCGetStatus, and KCGetIndKeychain to indicate that the specified keychain was not found.
errKCInvalidKeychain-25295Returned by the functions KCUnlock, KCSetDefaultKeychain, KCGetStatus, KCGetKeychainName, KCChangeSettings, and KCCreateKeychain to indicate that the keychain is not valid.
errKCDuplicateKeychain-25296Returned by the function KCCreateKeychain to indicate that your application tried to create a keychain that already exists.
errKCDuplicateCallback-25297Returned by the function KCAddCallback to indicate that your callback function was already registered.
errKCInvalidCallback-25298Returned by the function KCRemoveCallback to indicate that the callback function was not previously registered.
errKCDuplicateItem-25299Returned by the functions KCAddAppleSharePassword, KCAddInternetPassword, KCAddInternetPasswordWithPath, KCAddGenericPassword, and KCAddItem to indicate that you tried to add an existing keychain item to the keychain.
errKCItemNotFound-25300Returned by the functions KCFindAppleSharePassword, KCFindInternetPassword, KCFindInternetPasswordWithPath, KCFindGenericPassword, KCFindNextItem, and KCFindFirstItem to indicate that no matching item was found.
errKCBufferTooSmall-25301Returned by the functions KCFindAppleSharePassword, KCFindInternetPassword, KCFindInternetPasswordWithPath, KCFindGenericPassword, KCGetAttribute, KCGetData, and KCFindX509Certificates to indicate that the buffer was not large enough to contain the password data.
errKCDataTooLarge-25302Returned by the functions KCAddAppleSharePassword, KCAddInternetPassword, KCAddInternetPasswordWithPath, KCAddGenericPassword, KCSetAttribute, and KCSetData to indicate that the data is too large.
errKCNoSuchAttr-25303Returned by the functions KCSetAttribute, KCGetAttribute, and KCFindFirstItem to indicate that no such attribute exists.
errKCInvalidItemRef-25304Returned by the functions KCSetAttribute, KCGetAttribute, KCSetData, KCGetData, KCAddItem, KCDeleteItem, KCUpdateItem, KCCopyItem, and KCGetKeychain to indicate that the keychain item reference is invalid.
errKCInvalidSearchRef-25305Returned by the functions KCFindNextItem and KCReleaseSearch to indicate that the specified search reference is invalid.
errKCNoSuchClass-25306Returned by the function KCCopyItem to indicate that the item class does not exist.
errKCNoDefaultKeychain-25307Returned by the functions KCChangeSettings, KCSetDefaultKeychain, KCGetDefaultKeychain, KCAddAppleSharePassword, KCAddInternetPassword, KCAddInternetPasswordWithPath, KCAddGenericPassword, KCFindAppleSharePassword, KCFindInternetPassword, KCFindInternetPasswordWithPath, KCFindGenericPassword, KCCopyItem, KCAddItem, KCDeleteItem, KCUpdateItem, KCFindNextItem, KCFindFirstItem, and KCFindX509Certificates to indicate that there is no default keychain.
errKCInteractionNotAllowed-25308Returned by the functions KCCreateKeychain, KCChangeSettings, KCUnlock, and KCGetData (the latter two only when the Unlock Dialog and Allow Access dialog boxes are needed) to indicate that there is no start-up keychain.
errKCReadOnlyAttr-25309Returned by the function KCSetAttribute to indicate that the keychain item attribute is read-only.
errKCWrongKCVersion-25310Indicates that the wrong version of Keychain Manager is installed to perform this operation.
errKCKeySizeNotAllowed-25311Indicates that the key size is illegal.
errKCNoStorageModule-25312Returned by functions that prompts the loading of the Keychain Manager to indicate that the storage module is not found.
errKCNoCertificateModule-25313Returned when a function is required for a certificate and the certificate module is not found.
errKCNoPolicyModule-25314Returned when a function is required for a trust policy and the policy module is not found.
errKCInteractionRequired-25315Returned by the function KCUnlock to indicate that user interaction is required for this operation.
errKCDataNotAvailable-25316Indicates that the requested data is not available.
errKCDataNotModifiable-25317Returned by the functions KCSetData and KCGetData to indicate that the data cannot be modified.
errKCCreateChainFailed-25318Returned by the functions KCChooseCertificate and KCFindX509Certificates to indicate that the attempt to create a new keychain failed.

LockDefaultKeyChain
method, KeyChain Plugin version: 2.6 Mi, 4. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Locks the default keychain.
Notes:
Your application should not call LockDefaultKeyChain unless you are responding to a user's request to lock a keychain. In general, you should leave the keychain unlocked so that the user does not have to unlock it again in another application.

LastError is set.

NewKeyChainItemMemory(class as string,creator as string,data as memoryblock) as KeyChainItem
method, KeyChain Plugin version: 2.6 Di, 3. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Creates a new KeyChainItem Object with the given data.
Notes:
Values for the class parameter which defines the type of the item:

kCertificateKCItemClass"cert"Specifies that the item is a digital certificate.
kAppleSharePasswordKCItemClass"ashp"Specifies that the item is an AppleShare password.
kInternetPasswordKCItemClass"inet"Specifies that the item is an Internet password.
kGenericPasswordKCItemClass"genp"Specifies that the item is a generic password.

The creator parameter is the creator code of the application that owns this item.
Data is the data which is saved inside the item.

LastError is set.

NewKeyChainItemString(class as string,creator as string,data as string) as KeyChainItem
method, KeyChain Plugin version: 2.6 Di, 3. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Creates a new KeyChainItem Object with the given data.
Notes:
Values for the class parameter which defines the type of the item:

kCertificateKCItemClass"cert"Specifies that the item is a digital certificate.
kAppleSharePasswordKCItemClass"ashp"Specifies that the item is an AppleShare password.
kInternetPasswordKCItemClass"inet"Specifies that the item is an Internet password.
kGenericPasswordKCItemClass"genp"Specifies that the item is a generic password.

The creator parameter is the creator code of the application that owns this item.
Data is the data which is saved inside the item.

LastError is set.

OpenDefaultKeyChain as KeyChain
method, KeyChain Plugin version: 2.6 So, 1. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Obtains the default keychain.
Notes: LastError is set.

OpenIndexedKeyChain(index as integer) as KeyChain
method, KeyChain Plugin version: 2.6 So, 1. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Obtains the reference to an indexed keychain.
Notes:
Pass a value between 1 and the number returned by the function CountKeychains for the index parameter.

To guarantee correct operation, you should call the function CountKeychains once before calling OpenIndexedKeyChain.

LastError is set.

UnlockDefaultKeyChain(password as string) as boolean
method, KeyChain Plugin version: 2.6 So, 1. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Works.
Function: Displays a dialog box that prompts the user for a password in order before unlocking keychain.
Notes:
In most cases, your application does not need to call the Unlock functions directly, since most Keychain Manager functions that require an unlocked keychain call Unlock automatically. If your application needs to verify that a keychain is unlocked, use the property DefaultKeyChainStatus.

LastError is set.

Version as integer
property, KeyChain Plugin version: 2.6 So, 1. Sep 2002
Mac OS Classic: Works. Mac OS Carbon: Works. Windows: Allways 0.
Function: The version number of the keychain manager.
Notes: Lasterror is set.

Contact

Written 2002 by Christian Schmitz. Feel free to ask or report mistakes to realbasic@macsw.de.
Thanks.

This resource fork intentionally left blank ˇˇ